Miscellaneous Routines "You yourself are much condemned to have an itching palm; to sell and mart your offices for Gold." Shakespeare, Julius Caesar IV.3 Introduction The GoldMISC unit contains a grab-bag of miscellaneous procedures and functions that really do not call for an entire unit of their own. They may, one day, grow up and have their own units. Some of these routines were developed to support other units, and may be of little value to you on a regular basis. Nonetheless, they are here if you need them. The routines are organized into three categories: File, Printer and Misc. File Routines FSize(Filename:string): longint; Returns a longint indicating the size of the file in bytes. If the FileName passed is not found, a -1 value is returned. FileDrive(Full:string): string; Extracts and returns the drive letter (without the colon) from a filename. If the passed string parameter does not include a drive, a null is returned, i.e. ''. FileExt(Full:string): string; Extracts the file extension (excluding the period) from a filename. If the passed string parameter does not include an extension, a null is returned, i.e. ''. FileDirectory(Full:string): string; Extracts the directory path (without the drive letter) from a filename. If the passed string parameter does not include an extension, a null is returned, i.e. ''. The trailing backslash is always removed. FileName(Full:string): string; Extracts the file name (excluding the extension) from a filename. If the passed string parameter does not include an extension, a null is returned, i.e. ''. SlashedDirectory(Dir:string):string; This function is useful for building fully-qualified filenames. The passed directory name is returned, with a backslash added if the string did not already terminate with a backslash or colon. ParentDirectory(Dir:string): string; Returns the name of the parent to the directory string passed. If only the root directory is passed then the root is returned. A null string is returned if the string passed does not contain a parent. SmartMakeDir(DirectStr: PathStr): integer; Parses the passed string and creates each subdirectory as it progresses. The final product is a newly created (or nested) subdirectory. The passed string must follow the DOS naming conventions. Failures are recorded in LastMiscError. Exist(Filename:string):boolean; Returns true if the filename can be found. The passed string must follow all the DOS naming conventions. DeleteFile(Filename:string): shortint; Designed to delete the filename passed, this function returns a shortint value indicating the results of the routine, as follows: -1 - File not found 0 - File deleted {success} 1 - Error - file not deleted. RenameFile(Oldname,NewName:string):shortint; Attempts to rename the old filename to the new filename. Returns a shortint value indicating the results, as follows: 0 - File renamed {success} 1 - File not found 2 - Rename failed CopyFile(SourceFile, TargetFile:string): shortint; Copies a file like the DOS copy command. If a file with the same name as the Target already exists, it will be overwritten. The function returns one of the following byte values: 0 - Successful 1 - Source and Target are the same 2 - Cannot open source 3 - Unable to create target 4 - Error during copy Printer Routines The GoldMISC unit includes the following printer related routines: PrinterStatus:byte; This function is designed to indicate whether or not a parallel printer is attached and on-line. The global variable MiscVARS.LPTport indicates which port to test. Set MiscVARS.LPTport to 0 for LPT1 (default), 1 for LPT2, etc. The function returns one of the following byte values to indicate the status of the printer: 0 - Printer ready 1 - No paper 2 - Off line 3 - Busy 4 - Undetermined error AlternatePrinterStatus:byte; This function is very similar in operation to PrinterStatus but uses a slightly different technique. If you have problems using PrinterStatus with some weirdo printer, try this function instead. PrinterReady :boolean; This function returns true if a printer is detected as being on-line and ready. PrintScreen; This procedure emulates the user pressing the PrtScr key, and dumps the visible display to the printer port. ResetPrinter; This procedure should reset any printer back to its default (boot-up) settings. Memory Info It is not a good idea to use every scrap of available memory on the heap, as your program will tend to be unstable. Also, with no memory left, it is difficult to display information to the user advising him/her of the low memory. The GoldMISC unit includes a longint variable, MiscVARS.GoldMemBuffer, with a default value of 10,000 bytes. This represents the amount of memory which will be left free when Gold routines try to allocate memory on the heap. You may change the value as necessary. The following functions should be used in preference to MemAvail and MaxAvail: GoldMaxAvail:longint; After deducting the amount of memory reserved by MiscVars.GoldMemBuffer, this routine returns the size of the largest contiguous amount of free memory. GoldMemAvail:longint; After deducting the amount of memory reserved by MiscVars.GoldMemBuffer, this routine returns the total amount of free memory. Sounds The GoldMISC unit includes the following sound routines: Beep; You guessed! This function emits a brief, but nonetheless irritating, beep from the PC speaker. Ding; Teensy Weensy little noise. Thunk; Somewhat negative sounding, like wrong key press. Trill; Great feedback. It indicates success. Executing Other Programs The three routines listed below can be used to execute another program or application from within the active application. IMPORTANT NOTE: You must use the $M compiler directive to instruct Borland Pascal to leave some memory for the spawned or child program, e.g.{$M $8192,$8192,$8192}. The precise values depend on the size of your program, so experiment to determine the optimum settings. If the child process runs OK, try smaller values. If the child process doesn't run, try larger values. RunEXECOM(Progname, Params: string):integer; Executes an EXE or COM file as a child process. Pass two parameters, the name of the program and the optional parameters. Returns an integer value indicating the returned DosError value; a zero indicates success. RunDOS(Msg:string):integer; Starts a secondary copy of COMMAND.COM. One parameter is passed which is the message provided to the user. Returns an integer value indicating the returned DosError value; a zero indicates success. RunAnything(Command: string):integer; Spawns a child process from your application. Use this to run non-executables such as batch files. Returns an integer value indicating the returned DosError value; a zero indicates success. Development Tools If you look at any of the demo programs, you will find the HeapRecord and HeapCheck routines used in each one. These routines are designed to identify memory leaks in an application. If the application finishes with less memory than when it started, an error message is displayed. These routines were used extensively during Gold's development! Memory leaks can occur, for example, when you forget to call the function DisposeFields having created and used a form. When you are developing applications, make it a habit to use these routines to make sure that you have disposed of all memory you used. HeapRecord; Records the amount of available memory when the routine is called. Call this procedure as the first statement in an application. HeapCheck; Records the amount of available memory when the routine is called and compares it to the amount recorded by HeapRecord. Differences are displayed on screen. Calling this routine without first calling HeapRecord has no effect. Clearly you don't want these routines to be left in the production code. If you have a memory leak in your application, you certainly don't want your customer to see it! You should consider placing these calls inside conditional defines. The following code fragment illustrates this technique. begin {$IFOPT D+} HeapRecord; {$ENDIF} InitVars; SetScreen; SetFields; MouseShow(true); AssignHindHook(MyHindHook); ProcessInput(1); DisposeFields; DisposeForms; MouseShow(false); clrscr; {$IFOPT D+} HeapCheck; {$ENDIF} end. Miscellaneous Here are the routines that don't fit into any specific category: GetBitStatus(B:byte;BitPos:byte): boolean; Returns the status of a single bit contained within a byte. You store and retrieve up to 8 boolean values in a single byte; these are numbered 0 through 7. SetBitStatus(var Val:byte; BitPos:byte; On:boolean); Used to change the value of a single bit within a byte. Swap(var A,B:longint); Switches the values of A and B. WithinRange(Min,Max,Test: longint): boolean; Determines whether or not the value contained in Test falls between the upper and lower limits set in Min and Max and returns an appropriate true or false value. GetMin(Value1,Value2:longint): longint; Returns the smallest of the two passed values. GetMax(Value1,Value2:longint): longint; Returns the largest of the two values passed. ParamLine: string; Returns the entire parameter line as a space-delimited string, i.e. all the parameters specified by the user on the command line when the application was executed. ParamVal(Marker:string): string; Searches for Marker in the command line and returns all characters following the string up to the next occurrence of the marker. Frequency(Match:string;Source:string): byte; Returns the number of times that Match occurs in Source. BadCharPos(Str:string): integer; This function is used for checking for invalid filename characters in a string. The function returns the character position of the first illegal character, or 0 if no illegal characters were encountered. ValidFileName(FN:string): shortint; Verifies whether a filename is valid. Refer to the Reference for a list of the possible return codes. LastMiscError: integer; Dealing with memory and DOS shells certainly leaves an application open to failure. LastMiscError should be checked regularly to determine whether the last call to a GoldMISC function was successful. El blanko pageo on purpuso